

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>10. Python interface to LIGGGHTS(R)-PUBLIC &mdash; LIGGGHTS v3.X documentation</title>
  

  
  
  
  

  

  
  
    

  

  
  
    <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  

  

  
    <link rel="top" title="LIGGGHTS v3.X documentation" href="index.html"/>
        <link rel="next" title="11. Errors" href="Section_errors.html"/>
        <link rel="prev" title="9. Modifying &amp; extending LIGGGHTS(R)-PUBLIC" href="Section_modify.html"/> 

  
  <script src="_static/js/modernizr.min.js"></script>

</head>

<body class="wy-body-for-nav" role="document">

   
  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search">
          

          
            <a href="Manual.html" class="icon icon-home"> LIGGGHTS
          

          
          </a>

          
            
            
              <div class="version">
                v3.X
              </div>
            
          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_input_script.html">3. Input Script</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">4. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_gran_models.html">5. Contact models</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_mesh_modules.html">6. Mesh modules</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">7. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">8. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">9. Modifying &amp; extending LIGGGHTS(R)-PUBLIC</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">10. Python interface to LIGGGHTS(R)-PUBLIC</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#building-liggghts-r-public-as-a-shared-library">10.1. Building LIGGGHTS(R)-PUBLIC as a shared library</a></li>
<li class="toctree-l2"><a class="reference internal" href="#installing-the-python-wrapper-into-python">10.2. Installing the Python wrapper into Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="#extending-python-with-mpi-to-run-in-parallel">10.3. Extending Python with MPI to run in parallel</a></li>
<li class="toctree-l2"><a class="reference internal" href="#testing-the-python-liggghts-r-public-interface">10.4. Testing the Python-LIGGGHTS(R)-PUBLIC interface</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#test-liggghts-r-public-and-python-in-serial">10.4.1. <strong>Test LIGGGHTS(R)-PUBLIC and Python in serial:</strong></a></li>
<li class="toctree-l3"><a class="reference internal" href="#test-liggghts-r-public-and-python-in-parallel">10.4.2. <strong>Test LIGGGHTS(R)-PUBLIC and Python in parallel:</strong></a></li>
<li class="toctree-l3"><a class="reference internal" href="#running-python-scripts">10.4.3. <strong>Running Python scripts:</strong></a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#using-liggghts-r-public-from-python">10.5. Using LIGGGHTS(R)-PUBLIC from Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="#example-python-scripts-that-use-liggghts-r-public">10.6. Example Python scripts that use LIGGGHTS(R)-PUBLIC</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">11. Errors</a></li>
</ul>

            
          
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="Manual.html">LIGGGHTS</a>
        
      </nav>


      
      <div class="wy-nav-content">
        <div class="rst-content">
          















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="Manual.html">Docs</a> &raquo;</li>
        
      <li>10. Python interface to LIGGGHTS(R)-PUBLIC</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            <a href="_sources/Section_python.txt" rel="nofollow"> View page source</a>
          
          <a href="http://www.cfdem.com"> Website</a>
          
            <a href="Section_commands.html#comm" rel="nofollow"> Commands</a>
            
          
        
      </li>
    
  </ul>

  
  <hr/>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="Section_errors.html" class="btn btn-neutral float-right" title="11. Errors" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="Section_modify.html" class="btn btn-neutral" title="9. Modifying &amp; extending LIGGGHTS(R)-PUBLIC" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="python-interface-to-liggghts-r-public">
<h1>10. Python interface to LIGGGHTS(R)-PUBLIC<a class="headerlink" href="#python-interface-to-liggghts-r-public" title="Permalink to this headline">¶</a></h1>
<p>This section describes how to build and use LIGGGHTS(R)-PUBLIC via a Python
interface.</p>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#building-liggghts-r-public-as-a-shared-library" id="id6">Building LIGGGHTS(R)-PUBLIC as a shared library</a></li>
<li><a class="reference internal" href="#installing-the-python-wrapper-into-python" id="id7">Installing the Python wrapper into Python</a></li>
<li><a class="reference internal" href="#extending-python-with-mpi-to-run-in-parallel" id="id8">Extending Python with MPI to run in parallel</a></li>
<li><a class="reference internal" href="#testing-the-python-liggghts-r-public-interface" id="id9">Testing the Python-LIGGGHTS(R)-PUBLIC interface</a></li>
<li><a class="reference internal" href="#using-liggghts-r-public-from-python" id="id10">Using LIGGGHTS(R)-PUBLIC from Python</a></li>
<li><a class="reference internal" href="#example-python-scripts-that-use-liggghts-r-public" id="id11">Example Python scripts that use LIGGGHTS(R)-PUBLIC</a></li>
</ul>
</div>
<p>The LIGGGHTS(R)-PUBLIC distribution includes the file python/liggghts.py which wraps
the library interface to LIGGGHTS(R)-PUBLIC.  This file makes it is possible to
run LIGGGHTS(R)-PUBLIC, invoke LIGGGHTS(R)-PUBLIC commands or give it an input script, extract
LIGGGHTS(R)-PUBLIC results, an modify internal LIGGGHTS(R)-PUBLIC variables, either from a
Python script or interactively from a Python prompt.  You can do the
former in serial or parallel.  Running Python interactively in
parallel does not generally work, unless you have a package installed
that extends your Python to enable multiple instances of Python to
read what you type.</p>
<p><a class="reference external" href="http://www.python.org">Python</a> is a powerful scripting and programming
language which can be used to wrap software like LIGGGHTS(R)-PUBLIC and other
packages.  It can be used to glue multiple pieces of software
together, e.g. to run a coupled or multiscale model.  See <a class="reference internal" href="Section_howto.html#howto-10"><span>Section section</span></a> of the manual and the couple
directory of the distribution for more ideas about coupling LIGGGHTS(R)-PUBLIC to
other codes.  See <a class="reference internal" href="Section_start.html#start-5"><span>Section_start 4</span></a> about
how to build LIGGGHTS(R)-PUBLIC as a library, and <a class="reference internal" href="Section_howto.html#howto-10"><span>Section_howto 19</span></a> for a description of the library
interface provided in src/library.cpp and src/library.h and how to
extend it for your needs.  As described below, that interface is what
is exposed to Python.  It is designed to be easy to add functions to.
This can easily extend the Python inteface as well.  See details
below.</p>
<p>By using the Python interface, LIGGGHTS(R)-PUBLIC can also be coupled with a GUI
or other visualization tools that display graphs or animations in real
time as LIGGGHTS(R)-PUBLIC runs.  Examples of such scripts are inlcluded in the
python directory.</p>
<p>Two advantages of using Python are how concise the language is, and
that it can be run interactively, enabling rapid development and
debugging of programs.  If you use it to mostly invoke costly
operations within LIGGGHTS(R)-PUBLIC, such as running a simulation for a
reasonable number of timesteps, then the overhead cost of invoking
LIGGGHTS(R)-PUBLIC thru Python will be negligible.</p>
<p>Before using LIGGGHTS(R)-PUBLIC from a Python script, you need to do two things.
You need to build LIGGGHTS(R)-PUBLIC as a dynamic shared library, so it can be
loaded by Python.  And you need to tell Python how to find the library
and the Python wrapper file python/liggghts.py.  Both these steps are
discussed below.  If you wish to run LIGGGHTS(R)-PUBLIC in parallel from Python,
you also need to extend your Python with MPI.  This is also discussed
below.</p>
<p>The Python wrapper for LIGGGHTS(R)-PUBLIC uses the amazing and magical (to me)
&#8220;ctypes&#8221; package in Python, which auto-generates the interface code
needed between Python and a set of C interface routines for a library.
Ctypes is part of standard Python for versions 2.5 and later.  You can
check which version of Python you have installed, by simply typing
&#8220;python&#8221; at a shell prompt.</p>
<div class="section" id="building-liggghts-r-public-as-a-shared-library">
<span id="py-1"></span><h2><a class="toc-backref" href="#id6">10.1. Building LIGGGHTS(R)-PUBLIC as a shared library</a><a class="headerlink" href="#building-liggghts-r-public-as-a-shared-library" title="Permalink to this headline">¶</a></h2>
<p>Instructions on how to build LIGGGHTS(R)-PUBLIC as a shared library are given in
<a class="reference internal" href="Section_start.html#start-5"><span>Section_start 5</span></a>.  A shared library is one
that is dynamically loadable, which is what Python requires.  On Linux
this is a library file that ends in &#8221;.so&#8221;, not &#8221;.a&#8221;.</p>
<p>From the src directory, type</p>
<div class="highlight-python"><div class="highlight"><pre>make makeshlib
make -f Makefile.shlib foo
</pre></div>
</div>
<p>where foo is the machine target name, such as auto or mpi or serial.
This should create the file liblmp_foo.so in the src directory, as
well as a soft link libliggghts.so, which is what the Python wrapper will
load by default.  Note that if you are building multiple machine
versions of the shared library, the soft link is always set to the
most recently built version.</p>
<p>If this fails, see <a class="reference internal" href="Section_start.html#start-5"><span>Section_start 5</span></a> for
more details, especially if your LIGGGHTS(R)-PUBLIC build uses auxiliary libraries
like MPI or FFTW which may not be built as shared libraries on your
system.</p>
<hr class="docutils" />
</div>
<div class="section" id="installing-the-python-wrapper-into-python">
<span id="py-2"></span><h2><a class="toc-backref" href="#id7">10.2. Installing the Python wrapper into Python</a><a class="headerlink" href="#installing-the-python-wrapper-into-python" title="Permalink to this headline">¶</a></h2>
<p>For Python to invoke LIGGGHTS(R)-PUBLIC, there are 2 files it needs to know about:</p>
<ul class="simple">
<li>python/liggghts.py</li>
<li>src/libliggghts.so</li>
</ul>
<p>Lammps.py is the Python wrapper on the LIGGGHTS(R)-PUBLIC library interface.
Libliggghts.so is the shared LIGGGHTS(R)-PUBLIC library that Python loads, as
described above.</p>
<p>You can insure Python can find these files in one of two ways:</p>
<ul class="simple">
<li>set two environment variables</li>
<li>run the python/install.py script</li>
</ul>
<p>If you set the paths to these files as environment variables, you only
have to do it once.  For the csh or tcsh shells, add something like
this to your ~/.cshrc file, one line for each of the two files:</p>
<div class="highlight-python"><div class="highlight"><pre>setenv PYTHONPATH $*PYTHONPATH*:/home/sjplimp/liggghts/python
setenv LD_LIBRARY_PATH $*LD_LIBRARY_PATH*:/home/sjplimp/liggghts/src
</pre></div>
</div>
<p>If you use the python/install.py script, you need to invoke it every
time you rebuild LIGGGHTS(R)-PUBLIC (as a shared library) or make changes to the
python/liggghts.py file.</p>
<p>You can invoke install.py from the python directory as</p>
<div class="highlight-python"><div class="highlight"><pre>% python install.py [libdir] [pydir]
</pre></div>
</div>
<p>The optional libdir is where to copy the LIGGGHTS(R)-PUBLIC shared library to; the
default is /usr/local/lib.  The optional pydir is where to copy the
liggghts.py file to; the default is the site-packages directory of the
version of Python that is running the install script.</p>
<p>Note that libdir must be a location that is in your default
LD_LIBRARY_PATH, like /usr/local/lib or /usr/lib.  And pydir must be a
location that Python looks in by default for imported modules, like
its site-packages dir.  If you want to copy these files to
non-standard locations, such as within your own user space, you will
need to set your PYTHONPATH and LD_LIBRARY_PATH environment variables
accordingly, as above.</p>
<p>If the install.py script does not allow you to copy files into system
directories, prefix the python command with &#8220;sudo&#8221;.  If you do this,
make sure that the Python that root runs is the same as the Python you
run.  E.g. you may need to do something like</p>
<div class="highlight-python"><div class="highlight"><pre>% sudo /usr/local/bin/python install.py [libdir] [pydir]
</pre></div>
</div>
<p>You can also invoke install.py from the make command in the src
directory as</p>
<div class="highlight-python"><div class="highlight"><pre>% make install-python
</pre></div>
</div>
<p>In this mode you cannot append optional arguments.  Again, you may
need to prefix this with &#8220;sudo&#8221;.  In this mode you cannot control
which Python is invoked by root.</p>
<p>Note that if you want Python to be able to load different versions of
the LIGGGHTS(R)-PUBLIC shared library (see <a class="reference internal" href="#py-5"><span>this section</span></a> below), you will
need to manually copy files like liblmp_auto.so into the appropriate
system directory.  This is not needed if you set the LD_LIBRARY_PATH
environment variable as described above.</p>
<hr class="docutils" />
</div>
<div class="section" id="extending-python-with-mpi-to-run-in-parallel">
<span id="py-3"></span><h2><a class="toc-backref" href="#id8">10.3. Extending Python with MPI to run in parallel</a><a class="headerlink" href="#extending-python-with-mpi-to-run-in-parallel" title="Permalink to this headline">¶</a></h2>
<p>If you wish to run LIGGGHTS(R)-PUBLIC in parallel from Python, you need to extend
your Python with an interface to MPI.  This also allows you to
make MPI calls directly from Python in your script, if you desire.</p>
<p>There are several Python packages available that purport to wrap MPI
as a library and allow MPI functions to be called from Python.</p>
<p>These include</p>
<ul class="simple">
<li><a class="reference external" href="http://pympi.sourceforge.net/">pyMPI</a></li>
<li><a class="reference external" href="http://code.google.com/p/maroonmpi/">maroonmpi</a></li>
<li><a class="reference external" href="http://code.google.com/p/mpi4py/">mpi4py</a></li>
<li><a class="reference external" href="http://nbcr.sdsc.edu/forum/viewtopic.php?t=89&amp;sid=c997fefc3933bd66204875b436940f16">myMPI</a></li>
<li><a class="reference external" href="http://code.google.com/p/pypar">Pypar</a></li>
</ul>
<p>All of these except pyMPI work by wrapping the MPI library and
exposing (some portion of) its interface to your Python script.  This
means Python cannot be used interactively in parallel, since they do
not address the issue of interactive input to multiple instances of
Python running on different processors.  The one exception is pyMPI,
which alters the Python interpreter to address this issue, and (I
believe) creates a new alternate executable (in place of &#8220;python&#8221;
itself) as a result.</p>
<p>In principle any of these Python/MPI packages should work to invoke
LIGGGHTS(R)-PUBLIC in parallel and MPI calls themselves from a Python script which
is itself running in parallel.  However, when I downloaded and looked
at a few of them, their documentation was incomplete and I had trouble
with their installation.  It&#8217;s not clear if some of the packages are
still being actively developed and supported.</p>
<p>The one I recommend, since I have successfully used it with LIGGGHTS(R)-PUBLIC, is
Pypar.  Pypar requires the ubiquitous <a class="reference external" href="http://numpy.scipy.org">Numpy package</a> be installed in your Python.  After
launching python, type</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">numpy</span>
</pre></div>
</div>
<p>to see if it is installed.  If not, here is how to install it (version
1.3.0b1 as of April 2009).  Unpack the numpy tarball and from its
top-level directory, type</p>
<div class="highlight-python"><div class="highlight"><pre>python setup.py build
sudo python setup.py install
</pre></div>
</div>
<p>The &#8220;sudo&#8221; is only needed if required to copy Numpy files into your
Python distribution&#8217;s site-packages directory.</p>
<p>To install Pypar (version pypar-2.1.4_94 as of Aug 2012), unpack it
and from its &#8220;source&#8221; directory, type</p>
<div class="highlight-python"><div class="highlight"><pre>python setup.py build
sudo python setup.py install
</pre></div>
</div>
<p>Again, the &#8220;sudo&#8221; is only needed if required to copy Pypar files into
your Python distribution&#8217;s site-packages directory.</p>
<p>If you have successully installed Pypar, you should be able to run
Python and type</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">pypar</span>
</pre></div>
</div>
<p>without error.  You should also be able to run python in parallel
on a simple test script</p>
<div class="highlight-python"><div class="highlight"><pre>% mpirun -np 4 python test.py
</pre></div>
</div>
<p>where test.py contains the lines</p>
<div class="highlight-python"><div class="highlight"><pre>import pypar
print &quot;Proc %d out of %d procs&quot; % (pypar.rank(),pypar.size())
</pre></div>
</div>
<p>and see one line of output for each processor you run on.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">To use Pypar and LIGGGHTS(R)-PUBLIC in parallel from Python, you
must insure both are using the same version of MPI.  If you only have
one MPI installed on your system, this is not an issue, but it can be
if you have multiple MPIs.  Your LIGGGHTS(R)-PUBLIC build is explicit about which
MPI it is using, since you specify the details in your lo-level
src/MAKE/Makefile.foo file.  Pypar uses the &#8220;mpicc&#8221; command to find
information about the MPI it uses to build against.  And it tries to
load &#8220;libmpi.so&#8221; from the LD_LIBRARY_PATH.  This may or may not find
the MPI library that LIGGGHTS(R)-PUBLIC is using.  If you have problems running
both Pypar and LIGGGHTS(R)-PUBLIC together, this is an issue you may need to
address, e.g. by moving other MPI installations so that Pypar finds
the right one.</p>
</div>
<hr class="docutils" />
</div>
<div class="section" id="testing-the-python-liggghts-r-public-interface">
<span id="py-4"></span><h2><a class="toc-backref" href="#id9">10.4. Testing the Python-LIGGGHTS(R)-PUBLIC interface</a><a class="headerlink" href="#testing-the-python-liggghts-r-public-interface" title="Permalink to this headline">¶</a></h2>
<p>To test if LIGGGHTS(R)-PUBLIC is callable from Python, launch Python interactively
and type:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">liggghts</span> <span class="kn">import</span> <span class="n">liggghts</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">lig</span> <span class="o">=</span> <span class="n">liggghts</span><span class="p">()</span>
</pre></div>
</div>
<p>If you get no errors, you&#8217;re ready to use LIGGGHTS(R)-PUBLIC from Python.  If the
2nd command fails, the most common error to see is</p>
<div class="highlight-python"><div class="highlight"><pre>OSError: Could not load LIGGGHTS(R)-PUBLIC dynamic library
</pre></div>
</div>
<p>which means Python was unable to load the LIGGGHTS(R)-PUBLIC shared library.  This
typically occurs if the system can&#8217;t find the LIGGGHTS(R)-PUBLIC shared library or
one of the auxiliary shared libraries it depends on, or if something
about the library is incompatible with your Python.  The error message
should give you an indication of what went wrong.</p>
<p>You can also test the load directly in Python as follows, without
first importing from the liggghts.py file:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">ctypes</span> <span class="kn">import</span> <span class="n">CDLL</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">CDLL</span><span class="p">(</span><span class="s2">&quot;libliggghts.so&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>If an error occurs, carefully go thru the steps in <a class="reference internal" href="Section_start.html#start-5"><span>Section_start 5</span></a> and above about building a shared
library and about insuring Python can find the necessary two files
it needs.</p>
<div class="section" id="test-liggghts-r-public-and-python-in-serial">
<h3>10.4.1. <strong>Test LIGGGHTS(R)-PUBLIC and Python in serial:</strong><a class="headerlink" href="#test-liggghts-r-public-and-python-in-serial" title="Permalink to this headline">¶</a></h3>
<p>To run a LIGGGHTS(R)-PUBLIC test in serial, type these lines into Python
interactively from the bench directory:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">liggghts</span> <span class="kn">import</span> <span class="n">liggghts</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">lig</span> <span class="o">=</span> <span class="n">liggghts</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">lig</span><span class="o">.</span><span class="n">file</span><span class="p">(</span><span class="s2">&quot;in.lj&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>Or put the same lines in the file test.py and run it as</p>
<div class="highlight-python"><div class="highlight"><pre>% python test.py
</pre></div>
</div>
<p>Either way, you should see the results of running the in.lj benchmark
on a single processor appear on the screen, the same as if you had
typed something like:</p>
<div class="highlight-python"><div class="highlight"><pre>lmp_auto &lt; in.lj
</pre></div>
</div>
</div>
<div class="section" id="test-liggghts-r-public-and-python-in-parallel">
<h3>10.4.2. <strong>Test LIGGGHTS(R)-PUBLIC and Python in parallel:</strong><a class="headerlink" href="#test-liggghts-r-public-and-python-in-parallel" title="Permalink to this headline">¶</a></h3>
<p>To run LIGGGHTS(R)-PUBLIC in parallel, assuming you have installed the
<a class="reference external" href="http://datamining.anu.edu.au/~ole/pypar">Pypar</a> package as discussed
above, create a test.py file containing these lines:</p>
<div class="highlight-python"><div class="highlight"><pre>import pypar
from liggghts import liggghts
lig = liggghts()
lig.file(&quot;in.lj&quot;)
print &quot;Proc %d out of %d procs has&quot; % (pypar.rank(),pypar.size()),lig
pypar.finalize()
</pre></div>
</div>
<p>You can then run it in parallel as:</p>
<div class="highlight-python"><div class="highlight"><pre>% mpirun -np 4 python test.py
</pre></div>
</div>
<p>and you should see the same output as if you had typed</p>
<div class="highlight-python"><div class="highlight"><pre>% mpirun -np 4 lmp_auto &lt; in.lj
</pre></div>
</div>
<p>Note that if you leave out the 3 lines from test.py that specify Pypar
commands you will instantiate and run LIGGGHTS(R)-PUBLIC independently on each of
the P processors specified in the mpirun command.  In this case you
should get 4 sets of output, each showing that a LIGGGHTS(R)-PUBLIC run was made
on a single processor, instead of one set of output showing that
LIGGGHTS(R)-PUBLIC ran on 4 processors.  If the 1-processor outputs occur, it
means that Pypar is not working correctly.</p>
<p>Also note that once you import the PyPar module, Pypar initializes MPI
for you, and you can use MPI calls directly in your Python script, as
described in the Pypar documentation.  The last line of your Python
script should be pypar.finalize(), to insure MPI is shut down
correctly.</p>
</div>
<div class="section" id="running-python-scripts">
<h3>10.4.3. <strong>Running Python scripts:</strong><a class="headerlink" href="#running-python-scripts" title="Permalink to this headline">¶</a></h3>
<p>Note that any Python script (not just for LIGGGHTS(R)-PUBLIC) can be invoked in
one of several ways:</p>
<div class="highlight-python"><div class="highlight"><pre>% python foo.script
% python -i foo.script
% foo.script
</pre></div>
</div>
<p>The last command requires that the first line of the script be
something like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="ch">#!/usr/local/bin/python</span>
<span class="c1">#!/usr/local/bin/python -i</span>
</pre></div>
</div>
<p>where the path points to where you have Python installed, and that you
have made the script file executable:</p>
<div class="highlight-python"><div class="highlight"><pre>% chmod +x foo.script
</pre></div>
</div>
<p>Without the &#8220;-i&#8221; flag, Python will exit when the script finishes.
With the &#8220;-i&#8221; flag, you will be left in the Python interpreter when
the script finishes, so you can type subsequent commands.  As
mentioned above, you can only run Python interactively when running
Python on a single processor, not in parallel.</p>
</div>
</div>
<div class="section" id="using-liggghts-r-public-from-python">
<span id="py-5"></span><h2><a class="toc-backref" href="#id10">10.5. Using LIGGGHTS(R)-PUBLIC from Python</a><a class="headerlink" href="#using-liggghts-r-public-from-python" title="Permalink to this headline">¶</a></h2>
<p>The Python interface to LIGGGHTS(R)-PUBLIC consists of a Python &#8220;liggghts&#8221; module,
the source code for which is in python/liggghts.py, which creates a
&#8220;liggghts&#8221; object, with a set of methods that can be invoked on that
object.  The sample Python code below assumes you have first imported
the &#8220;liggghts&#8221; module in your Python script, as follows:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">liggghts</span> <span class="kn">import</span> <span class="n">liggghts</span>
</pre></div>
</div>
<p>These are the methods defined by the liggghts module.  If you look
at the file src/library.cpp you will see that they correspond
one-to-one with calls you can make to the LIGGGHTS(R)-PUBLIC library from a C++ or
C or Fortran program.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">lig</span> <span class="o">=</span> <span class="n">liggghts</span><span class="p">()</span>           <span class="c1"># create a LIGGGHTS(R)-PUBLIC object using the default libliggghts.so library</span>
<span class="n">lig</span> <span class="o">=</span> <span class="n">liggghts</span><span class="p">(</span><span class="s2">&quot;auto&quot;</span><span class="p">)</span>     <span class="c1"># create a LIGGGHTS(R)-PUBLIC object using the liblmp_auto.so library</span>
<span class="n">lig</span> <span class="o">=</span> <span class="n">liggghts</span><span class="p">(</span><span class="s2">&quot;&quot;</span><span class="p">,</span><span class="nb">list</span><span class="p">)</span>    <span class="c1"># ditto, with command-line args, e.g. list = [&quot;-echo&quot;,&quot;screen&quot;]</span>
<span class="n">lig</span> <span class="o">=</span> <span class="n">liggghts</span><span class="p">(</span><span class="s2">&quot;auto&quot;</span><span class="p">,</span><span class="nb">list</span><span class="p">)</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="n">lig</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>              <span class="c1"># destroy a LIGGGHTS(R)-PUBLIC object</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="n">lig</span><span class="o">.</span><span class="n">file</span><span class="p">(</span><span class="nb">file</span><span class="p">)</span>           <span class="c1"># run an entire input script, file = &quot;in.lj&quot;</span>
<span class="n">lig</span><span class="o">.</span><span class="n">command</span><span class="p">(</span><span class="n">cmd</span><span class="p">)</span>         <span class="c1"># invoke a single LIGGGHTS(R)-PUBLIC command, cmd = &quot;run 100&quot;</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="n">xlo</span> <span class="o">=</span> <span class="n">lig</span><span class="o">.</span><span class="n">extract_global</span><span class="p">(</span><span class="n">name</span><span class="p">,</span><span class="nb">type</span><span class="p">)</span>  <span class="c1"># extract a global quantity</span>
                                     <span class="c1"># name = &quot;boxxlo&quot;, &quot;nlocal&quot;, etc</span>
                                  <span class="c1"># type = 0 = int</span>
                                  <span class="c1">#        1 = double</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="n">coords</span> <span class="o">=</span> <span class="n">lig</span><span class="o">.</span><span class="n">extract_atom</span><span class="p">(</span><span class="n">name</span><span class="p">,</span><span class="nb">type</span><span class="p">)</span>      <span class="c1"># extract a per-atom quantity</span>
                                          <span class="c1"># name = &quot;x&quot;, &quot;type&quot;, etc</span>
                                       <span class="c1"># type = 0 = vector of ints</span>
                                       <span class="c1">#        1 = array of ints</span>
                                       <span class="c1">#        2 = vector of doubles</span>
                                       <span class="c1">#        3 = array of doubles</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="n">eng</span> <span class="o">=</span> <span class="n">lig</span><span class="o">.</span><span class="n">extract_compute</span><span class="p">(</span><span class="nb">id</span><span class="p">,</span><span class="n">style</span><span class="p">,</span><span class="nb">type</span><span class="p">)</span>  <span class="c1"># extract value(s) from a compute</span>
<span class="n">v3</span> <span class="o">=</span> <span class="n">lig</span><span class="o">.</span><span class="n">extract_fix</span><span class="p">(</span><span class="nb">id</span><span class="p">,</span><span class="n">style</span><span class="p">,</span><span class="nb">type</span><span class="p">,</span><span class="n">i</span><span class="p">,</span><span class="n">j</span><span class="p">)</span>   <span class="c1"># extract value(s) from a fix</span>
                                          <span class="c1"># id = ID of compute or fix</span>
                                       <span class="c1"># style = 0 = global data</span>
                                       <span class="c1">#         1 = per-atom data</span>
                                       <span class="c1">#         2 = local data</span>
                                       <span class="c1"># type = 0 = scalar</span>
                                       <span class="c1">#        1 = vector</span>
                                       <span class="c1">#        2 = array</span>
                                       <span class="c1"># i,j = indices of value in global vector or array</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="n">var</span> <span class="o">=</span> <span class="n">lig</span><span class="o">.</span><span class="n">extract_variable</span><span class="p">(</span><span class="n">name</span><span class="p">,</span><span class="n">group</span><span class="p">,</span><span class="n">flag</span><span class="p">)</span>  <span class="c1"># extract value(s) from a variable</span>
                                          <span class="c1"># name = name of variable</span>
                                          <span class="c1"># group = group ID (ignored for equal-style variables)</span>
                                          <span class="c1"># flag = 0 = equal-style variable</span>
                                          <span class="c1">#        1 = atom-style variable</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="n">natoms</span> <span class="o">=</span> <span class="n">lig</span><span class="o">.</span><span class="n">get_natoms</span><span class="p">()</span>                 <span class="c1"># total # of atoms as int</span>
<span class="n">data</span> <span class="o">=</span> <span class="n">lig</span><span class="o">.</span><span class="n">gather_atoms</span><span class="p">(</span><span class="n">name</span><span class="p">,</span><span class="nb">type</span><span class="p">,</span><span class="n">count</span><span class="p">)</span>  <span class="c1"># return atom attribute of all atoms gathered into data, ordered by atom ID</span>
                                          <span class="c1"># name = &quot;x&quot;, &quot;charge&quot;, &quot;type&quot;, etc</span>
                                          <span class="c1"># count = # of per-atom values, 1 or 3, etc</span>
<span class="n">lig</span><span class="o">.</span><span class="n">scatter_atoms</span><span class="p">(</span><span class="n">name</span><span class="p">,</span><span class="nb">type</span><span class="p">,</span><span class="n">count</span><span class="p">,</span><span class="n">data</span><span class="p">)</span>   <span class="c1"># scatter atom attribute of all atoms from data, ordered by atom ID</span>
                                          <span class="c1"># name = &quot;x&quot;, &quot;charge&quot;, &quot;type&quot;, etc</span>
                                          <span class="c1"># count = # of per-atom values, 1 or 3, etc</span>
</pre></div>
</div>
<hr class="docutils" />
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Currently, the creation of a LIGGGHTS(R)-PUBLIC object from within
liggghts.py does not take an MPI communicator as an argument.  There
should be a way to do this, so that the LIGGGHTS(R)-PUBLIC instance runs on a
subset of processors if desired, but I don&#8217;t know how to do it from
Pypar.  So for now, it runs with MPI_COMM_WORLD, which is all the
processors.  If someone figures out how to do this with one or more of
the Python wrappers for MPI, like Pypar, please let us know and we
will amend these doc pages.</p>
</div>
<p>Note that you can create multiple LIGGGHTS(R)-PUBLIC objects in your Python
script, and coordinate and run multiple simulations, e.g.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">liggghts</span> <span class="kn">import</span> <span class="n">liggghts</span>
<span class="n">lig1</span> <span class="o">=</span> <span class="n">liggghts</span><span class="p">()</span>
<span class="n">lig2</span> <span class="o">=</span> <span class="n">liggghts</span><span class="p">()</span>
<span class="n">lig1</span><span class="o">.</span><span class="n">file</span><span class="p">(</span><span class="s2">&quot;in.file1&quot;</span><span class="p">)</span>
<span class="n">lig2</span><span class="o">.</span><span class="n">file</span><span class="p">(</span><span class="s2">&quot;in.file2&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>The file() and command() methods allow an input script or single
commands to be invoked.</p>
<p>The extract_global(), extract_atom(), extract_compute(),
extract_fix(), and extract_variable() methods return values or
pointers to data structures internal to LIGGGHTS(R)-PUBLIC.</p>
<p>For extract_global() see the src/library.cpp file for the list of
valid names.  New names could easily be added.  A double or integer is
returned.  You need to specify the appropriate data type via the type
argument.</p>
<p>For extract_atom(), a pointer to internal LIGGGHTS(R)-PUBLIC atom-based data is
returned, which you can use via normal Python subscripting.  See the
extract() method in the src/atom.cpp file for a list of valid names.
Again, new names could easily be added.  A pointer to a vector of
doubles or integers, or a pointer to an array of doubles (double <a href="#id2"><span class="problematic" id="id3">**</span></a>)
or integers (int <a href="#id4"><span class="problematic" id="id5">**</span></a>) is returned.  You need to specify the appropriate
data type via the type argument.</p>
<p>For extract_compute() and extract_fix(), the global, per-atom, or
local data calulated by the compute or fix can be accessed.  What is
returned depends on whether the compute or fix calculates a scalar or
vector or array.  For a scalar, a single double value is returned.  If
the compute or fix calculates a vector or array, a pointer to the
internal LIGGGHTS(R)-PUBLIC data is returned, which you can use via normal Python
subscripting.  The one exception is that for a fix that calculates a
global vector or array, a single double value from the vector or array
is returned, indexed by I (vector) or I and J (array).  I,J are
zero-based indices.  The I,J arguments can be left out if not needed.
See <a class="reference internal" href="Section_howto.html#howto-8"><span>Section_howto 15</span></a> of the manual for a
discussion of global, per-atom, and local data, and of scalar, vector,
and array data types.  See the doc pages for individual
<a class="reference internal" href="compute.html"><em>computes</em></a> and <a class="reference internal" href="fix.html"><em>fixes</em></a> for a description of what
they calculate and store.</p>
<p>For extract_variable(), an <a class="reference internal" href="variable.html"><em>equal-style or atom-style variable</em></a> is evaluated and its result returned.</p>
<p>For equal-style variables a single double value is returned and the
group argument is ignored.  For atom-style variables, a vector of
doubles is returned, one value per atom, which you can use via normal
Python subscripting. The values will be zero for atoms not in the
specified group.</p>
<p>The get_natoms() method returns the total number of atoms in the
simulation, as an int.</p>
<p>The gather_atoms() method returns a ctypes vector of ints or doubles
as specified by type, of length count*natoms, for the property of all
the atoms in the simulation specified by name, ordered by count and
then by atom ID.  The vector can be used via normal Python
subscripting.  If atom IDs are not consecutively ordered within
LIGGGHTS(R)-PUBLIC, a None is returned as indication of an error.</p>
<p>Note that the data structure gather_atoms(&#8220;x&#8221;) returns is different
from the data structure returned by extract_atom(&#8220;x&#8221;) in four ways.
(1) Gather_atoms() returns a vector which you index as x[i];
extract_atom() returns an array which you index as x[i][j].  (2)
Gather_atoms() orders the atoms by atom ID while extract_atom() does
not.  (3) Gathert_atoms() returns a list of all atoms in the
simulation; extract_atoms() returns just the atoms local to each
processor.  (4) Finally, the gather_atoms() data structure is a copy
of the atom coords stored internally in LIGGGHTS(R)-PUBLIC, whereas extract_atom()
returns an array that effectively points directly to the internal
data.  This means you can change values inside LIGGGHTS(R)-PUBLIC from Python by
assigning a new values to the extract_atom() array.  To do this with
the gather_atoms() vector, you need to change values in the vector,
then invoke the scatter_atoms() method.</p>
<p>The scatter_atoms() method takes a vector of ints or doubles as
specified by type, of length count*natoms, for the property of all the
atoms in the simulation specified by name, ordered by bount and then
by atom ID.  It uses the vector of data to overwrite the corresponding
properties for each atom inside LIGGGHTS(R)-PUBLIC.  This requires LIGGGHTS(R)-PUBLIC to have
its &#8220;map&#8221; option enabled; see the <a class="reference internal" href="atom_modify.html"><em>atom_modify</em></a>
command for details.  If it is not, or if atom IDs are not
consecutively ordered, no coordinates are reset.</p>
<p>The array of coordinates passed to scatter_atoms() must be a ctypes
vector of ints or doubles, allocated and initialized something like
this:</p>
<div class="highlight-python"><div class="highlight"><pre>from ctypes import *
natoms = lig.get_natoms()
n3 = 3*natoms
x = (n3*c_double)()
x**0** = x coord of atom with ID 1
x**1** = y coord of atom with ID 1
x**2** = z coord of atom with ID 1
x**3** = x coord of atom with ID 2
...
x**n3-1** = z coord of atom with ID natoms
lig.scatter_coords(&quot;x&quot;,1,3,x)
</pre></div>
</div>
<p>Alternatively, you can just change values in the vector returned by
gather_atoms(&#8220;x&#8221;,1,3), since it is a ctypes vector of doubles.</p>
<hr class="docutils" />
<p>As noted above, these Python class methods correspond one-to-one with
the functions in the LIGGGHTS(R)-PUBLIC library interface in src/library.cpp and
library.h.  This means you can extend the Python wrapper via the
following steps:</p>
<ul class="simple">
<li>Add a new interface function to src/library.cpp and
src/library.h.</li>
<li>Rebuild LIGGGHTS(R)-PUBLIC as a shared library.</li>
<li>Add a wrapper method to python/liggghts.py for this interface
function.</li>
<li>You should now be able to invoke the new interface function from a
Python script.  Isn&#8217;t ctypes amazing?</li>
</ul>
</div>
<div class="section" id="example-python-scripts-that-use-liggghts-r-public">
<span id="py-6"></span><h2><a class="toc-backref" href="#id11">10.6. Example Python scripts that use LIGGGHTS(R)-PUBLIC</a><a class="headerlink" href="#example-python-scripts-that-use-liggghts-r-public" title="Permalink to this headline">¶</a></h2>
<p>These are the Python scripts included as demos in the python/examples
directory of the LIGGGHTS(R)-PUBLIC distribution, to illustrate the kinds of
things that are possible when Python wraps LIGGGHTS(R)-PUBLIC.  If you create your
own scripts, send them to us and we can include them in the LIGGGHTS(R)-PUBLIC
distribution.</p>
<table border="1" class="docutils">
<colgroup>
<col width="24%" />
<col width="76%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>trivial.py</td>
<td>read/run a LIGGGHTS(R)-PUBLIC input script thru Python</td>
</tr>
<tr class="row-even"><td>demo.py</td>
<td>invoke various LIGGGHTS(R)-PUBLIC library interface routines</td>
</tr>
<tr class="row-odd"><td>simple.py</td>
<td>mimic operation of couple/simple/simple.cpp in Python</td>
</tr>
<tr class="row-even"><td>gui.py</td>
<td>GUI go/stop/temperature-slider to control LIGGGHTS(R)-PUBLIC</td>
</tr>
<tr class="row-odd"><td>plot.py</td>
<td>real-time temeperature plot with GnuPlot via Pizza.py</td>
</tr>
<tr class="row-even"><td>viz_tool.py</td>
<td>real-time viz via some viz package</td>
</tr>
<tr class="row-odd"><td>vizplotgui_tool.py</td>
<td>combination of viz_tool.py and plot.py and gui.py</td>
</tr>
</tbody>
</table>
<hr class="docutils" />
<p>For the viz_tool.py and vizplotgui_tool.py commands, replace &#8220;tool&#8221;
with &#8220;gl&#8221; or &#8220;atomeye&#8221; or &#8220;pymol&#8221; or &#8220;vmd&#8221;, depending on what
visualization package you have installed.</p>
<p>Note that for GL, you need to be able to run the Pizza.py GL tool,
which is included in the pizza sub-directory.  See the <a class="reference external" href="http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py doc pages</a> for more info:</p>
<p>Note that for AtomEye, you need version 3, and there is a line in the
scripts that specifies the path and name of the executable.  See the
AtomEye WWW pages <a class="reference external" href="http://mt.seas.upenn.edu/Archive/Graphics/A">here</a> or <a class="reference external" href="http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html">here</a> for more details:</p>
<div class="highlight-python"><div class="highlight"><pre>http://mt.seas.upenn.edu/Archive/Graphics/A
http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html
</pre></div>
</div>
<p>The latter link is to AtomEye 3 which has the scriping
capability needed by these Python scripts.</p>
<p>Note that for PyMol, you need to have built and installed the
open-source version of PyMol in your Python, so that you can import it
from a Python script.  See the PyMol WWW pages <a class="reference external" href="http://www.pymol.org">here</a> or
<a class="reference external" href="http://sourceforge.net/scm/?type=svn&amp;group_id=4546">here</a> for more details:</p>
<div class="highlight-python"><div class="highlight"><pre>http://www.pymol.org
http://sourceforge.net/scm/?type=svn&amp;group_id=4546
</pre></div>
</div>
<p>The latter link is to the open-source version.</p>
<hr class="docutils" />
<p>See the python/README file for instructions on how to run them and the
source code for individual scripts for comments about what they do.</p>
<p>Here are screenshots of the vizplotgui_tool.py script in action for
different visualization package options.  Click to see larger images:</p>
</div>
</div>


           </div>
           <div class="articleComments">
            
           </div>
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="Section_errors.html" class="btn btn-neutral float-right" title="11. Errors" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="Section_modify.html" class="btn btn-neutral" title="9. Modifying &amp; extending LIGGGHTS(R)-PUBLIC" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2016, DCS Computing GmbH, JKU Linz and Sandia Corporation.

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. 

</footer>

        </div>
      </div>

    </section>

  </div>
  


  

    <script type="text/javascript">
        var DOCUMENTATION_OPTIONS = {
            URL_ROOT:'./',
            VERSION:'v3.X',
            LANGUAGE:'None',
            COLLAPSE_INDEX:false,
            FILE_SUFFIX:'.html',
            HAS_SOURCE:  true,
            SOURCELINK_SUFFIX: ''
        };
    </script>
      <script type="text/javascript" src="_static/jquery.js"></script>
      <script type="text/javascript" src="_static/underscore.js"></script>
      <script type="text/javascript" src="_static/doctools.js"></script>

  

  
  
    <script type="text/javascript" src="_static/js/theme.js"></script>
  

  
  
  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.StickyNav.enable();
      });
  </script>
   

</body>
</html>